From 20c1fb0a0a826e6ee85e333662b3c1178fe71542 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 3 Aug 2020 18:41:36 -0400 Subject: [PATCH] docs: Tweak documentation for list widgets Fix numerous cases of : vs :: for signal references, add some more details here and there. --- docs/reference/gtk/gtk4-sections.txt | 2 +- gtk/gtkcolumnviewcolumn.c | 10 +++++ gtk/gtkdirectorylist.c | 14 ++++--- gtk/gtkdropdown.c | 6 +-- gtk/gtkmultiselection.c | 2 +- gtk/gtknoselection.c | 2 +- gtk/gtkselectionmodel.c | 62 ++++++++++++++-------------- gtk/gtksignallistitemfactory.c | 12 +++--- gtk/gtksingleselection.c | 26 +++++++----- gtk/gtkstringlist.c | 4 +- 10 files changed, 77 insertions(+), 63 deletions(-) diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt index c6ef42f3e8..0efe0d7da7 100644 --- a/docs/reference/gtk/gtk4-sections.txt +++ b/docs/reference/gtk/gtk4-sections.txt @@ -431,7 +431,7 @@ gtk_single_selection_get_type
gtkmultiselection -GtkMultiSeledction +GtkMultiSelection GtkMultiSelection gtk_multi_selection_new gtk_multi_selection_get_model diff --git a/gtk/gtkcolumnviewcolumn.c b/gtk/gtkcolumnviewcolumn.c index c0aaf631bb..3ee4b84123 100644 --- a/gtk/gtkcolumnviewcolumn.c +++ b/gtk/gtkcolumnviewcolumn.c @@ -42,6 +42,13 @@ * @see_also: #GtkColumnView * * GtkColumnViewColumn represents the columns being added to #GtkColumnView. + * + * Columns have a title, and can optionally have a header menu set + * with gtk_column_view_column_set_header_menu(). + * + * A sorter can be associated with a column using + * gtk_column_view_column_set_sorter(), to let users influence sorting by + * clicking on the column header. */ struct _GtkColumnViewColumn @@ -756,6 +763,9 @@ gtk_column_view_column_remove_from_sorter (GtkColumnViewColumn *self) * * This sorter can be made active by clicking on the column * header, or by calling gtk_column_view_sort_by_column(). + * + * See gtk_column_view_get_sorter() for the necessary steps + * for setting up customizable sorting for #GtkColumnView. */ void gtk_column_view_column_set_sorter (GtkColumnViewColumn *self, diff --git a/gtk/gtkdirectorylist.c b/gtk/gtkdirectorylist.c index feb3ed044c..5ec5c94b0d 100644 --- a/gtk/gtkdirectorylist.c +++ b/gtk/gtkdirectorylist.c @@ -34,21 +34,22 @@ * It presents a #GListModel and fills it asynchronously with the #GFileInfos * returned from that function. * - * Enumeration will start automatically when a the GtkDirectoryList:file property + * Enumeration will start automatically when a the #GtkDirectoryList:file property * is set. * - * While the #GtkDirectoryList is being filled, the GtkDirectoryList:loading + * While the #GtkDirectoryList is being filled, the #GtkDirectoryList:loading * property will be set to %TRUE. You can listen to that property if you want * to show information like a #GtkSpinner or a "Loading..." text. - * If loading fails at any point, the GtkDirectoryList:error property will be set - * to give more indication about the failure. + * + * If loading fails at any point, the #GtkDirectoryList:error property will be + * set to give more indication about the failure. * * The #GFileInfos returned from a #GtkDirectoryList have the "standard::file" * attribute set to the #GFile they refer to. This way you can get at the file * that is referred to in the same way you would via g_file_enumerator_get_child(). * This means you do not need access to the #GtkDirectoryList but can access - * the #GFile directly from the #GFileInfo when operating with a #GtkListView or - * similar. + * the #GFile directly from the #GFileInfo when operating with a #GtkListView + * or similar. */ /* random number that everyone else seems to use, too */ @@ -817,6 +818,7 @@ gtk_directory_list_get_io_priority (GtkDirectoryList *self) * * Returns %TRUE if the children enumeration is currently in * progress. + * * Files will be added to @self from time to time while loading is * going on. The order in which are added is undefined and may change * inbetween runs. diff --git a/gtk/gtkdropdown.c b/gtk/gtkdropdown.c index 1ddf89448b..bb8c763d6c 100644 --- a/gtk/gtkdropdown.c +++ b/gtk/gtkdropdown.c @@ -58,13 +58,11 @@ * * The options are given to GtkDropDown in the form of #GListModel, * and how the individual options are represented is determined by - * a #GtkListItemFactory. The default factory displays simple strings, - * and expects to obtain these from the model by evaluating an expression - * that has to be provided via gtk_drop_down_set_expression(). + * a #GtkListItemFactory. The default factory displays simple strings. * * GtkDropDown knows how to obtain strings from the items in a * #GtkStringList; for other models, you have to provide an expression - * to find the strings. + * to find the strings via gtk_drop_down_set_expression(). * * GtkDropDown can optionally allow search in the popup, which is * useful if the list of options is long. To enable the search entry, diff --git a/gtk/gtkmultiselection.c b/gtk/gtkmultiselection.c index c6e3474cb9..70ee6ea8bb 100644 --- a/gtk/gtkmultiselection.c +++ b/gtk/gtkmultiselection.c @@ -347,7 +347,7 @@ gtk_multi_selection_class_init (GtkMultiSelectionClass *klass) gobject_class->dispose = gtk_multi_selection_dispose; /** - * GtkMultiSelection:model + * GtkMultiSelection:model: * * The list managed by this selection */ diff --git a/gtk/gtknoselection.c b/gtk/gtknoselection.c index 597eb4af31..1e9331bee2 100644 --- a/gtk/gtknoselection.c +++ b/gtk/gtknoselection.c @@ -31,7 +31,7 @@ * @Title: GtkNoSelection * @see_also: #GtkSelectionModel * - * GtkNoSelection is an implementation of the #GtkSelectionModel interface + * GtkNoSelection is an implementation of the #GtkSelectionModel interface * that does not allow selecting anything. * * This model is meant to be used as a simple wrapper to #GListModels when a diff --git a/gtk/gtkselectionmodel.c b/gtk/gtkselectionmodel.c index 0a60d7310d..f14676b912 100644 --- a/gtk/gtkselectionmodel.c +++ b/gtk/gtkselectionmodel.c @@ -31,40 +31,40 @@ * @Short_description: An extension of the list model interface that handles selections * @See_also: #GListModel, #GtkSingleSelection * - * #GtkSelectionModel is an interface that extends the #GListModel interface by adding - * support for selections. This support is then used by widgets using list models to add - * the ability to select and unselect various items. + * #GtkSelectionModel is an interface that extends the #GListModel interface by + * adding support for selections. This support is then used by widgets using list + * models to add the ability to select and unselect various items. * - * GTK provides default implementations of the mode common selection modes such as - * #GtkSingleSelection, so you will only need to implement this interface if you want - * detailed control about how selections should be handled. + * GTK provides default implementations of the most common selection modes such + * as #GtkSingleSelection, so you will only need to implement this interface if + * you want detailed control about how selections should be handled. * - * A #GtkSelectionModel supports a single boolean per item indicating if an item is selected - * or not. This can be queried via gtk_selection_model_is_selected(). When the selected - * state of one or more items changes, the model will emit the + * A #GtkSelectionModel supports a single boolean per item indicating if an item + * is selected or not. This can be queried via gtk_selection_model_is_selected(). + * When the selected state of one or more items changes, the model will emit the * #GtkSelectionModel::selection-changed signal by calling the - * gtk_selection_model_selection_changed() function. The positions given in that signal - * may have their selection state changed, though that is not a requirement. - * If new items added to the model via the #GListModel::items-changed signal are selected - * or not is up to the implementation. + * gtk_selection_model_selection_changed() function. The positions given in that + * signal may have their selection state changed, though that is not a requirement. + * If new items added to the model via the #GListModel::items-changed signal are + * selected or not is up to the implementation. * * Note that items added via #GListModel::items-changed may already be selected * and no #GtkSelectionModel::selection-changed will be emitted for them. So to * track which items are selected, it is necessary to listen to both signals. * - * Additionally, the interface can expose functionality to select and unselect items. - * If these functions are implemented, GTK's list widgets will allow users to select and - * unselect items. However, #GtkSelectionModels are free to only implement them - * partially or not at all. In that case the widgets will not support the unimplemented - * operations. + * Additionally, the interface can expose functionality to select and unselect + * items. If these functions are implemented, GTK's list widgets will allow users + * to select and unselect items. However, #GtkSelectionModels are free to only + * implement them partially or not at all. In that case the widgets will not + * support the unimplemented operations. * - * When selecting or unselecting is supported by a model, the return values of the - * selection functions do NOT indicate if selection or unselection happened. They are - * only meant to indicate complete failure, like when this mode of selecting is not - * supported by the model. + * When selecting or unselecting is supported by a model, the return values of + * the selection functions do *not* indicate if selection or unselection happened. + * They are only meant to indicate complete failure, like when this mode of + * selecting is not supported by the model. * - * Selections may happen asynchronously, so the only reliable way to find out when an - * item was selected is to listen to the signals that indicate selection. + * Selections may happen asynchronously, so the only reliable way to find out + * when an item was selected is to listen to the signals that indicate selection. */ G_DEFINE_INTERFACE (GtkSelectionModel, gtk_selection_model, G_TYPE_LIST_MODEL) @@ -251,7 +251,7 @@ gtk_selection_model_default_init (GtkSelectionModelInterface *iface) * Emitted when the selection state of some of the items in @model changes. * * Note that this signal does not specify the new selection state of the items, - * they need to be queried manually. + * they need to be queried manually. * It is also not necessary for a model to change the selection state of any of * the items in the selection model, though it would be rather useless to emit * such a signal. @@ -318,13 +318,13 @@ gtk_selection_model_get_selection (GtkSelectionModel *model) * @position: start of the queired range * @n_items: number of items in the queried range * - * Gets a set containing a set where the values in the range [position, - * position + n_items) match the selected state of the items in that range. + * Gets a set containing a set where the values in the range `[position, + * position + n_items)` match the selected state of the items in that range. * All values outside that range are undefined. * * This function is an optimization for gtk_selection_model_get_selection() when * you are only interested in part of the model's selected state. A common use - * case is in response to the :selection-changed signal. + * case is in response to the #GtkSelectionModel::selection-changed signal. * * Returns: A #GtkBitset that matches the selection state for the given state * with all other values being undefined. @@ -495,7 +495,7 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model) * are more likely to implement support for those. * * Requests that the selection state of all positions set in @mask be - * updated to the respecitve value in the @selected bitmask. + * updated to the respecitve value in the @selected bitmask. * * In pseudocode, it would look something like this: * @@ -544,8 +544,8 @@ gtk_selection_model_set_selection (GtkSelectionModel *model, * @n_items: the number of changed items * * Helper function for implementations of #GtkSelectionModel. - * Call this when a the selection changes to emit the ::selection-changed - * signal. + * Call this when a the selection changes to emit the + * #GtkSelectionModel::selection-changed signal. */ void gtk_selection_model_selection_changed (GtkSelectionModel *model, diff --git a/gtk/gtksignallistitemfactory.c b/gtk/gtksignallistitemfactory.c index c1c8ada1f6..d728abf84f 100644 --- a/gtk/gtksignallistitemfactory.c +++ b/gtk/gtksignallistitemfactory.c @@ -163,7 +163,7 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass) * The ::setup signal is emitted when a new listitem has been created and * needs to be setup for use. It is the first signal emitted for every listitem. * - * The GtkSignalListItemFactory::teardown signal is the opposite of this signal + * The #GtkSignalListItemFactory::teardown signal is the opposite of this signal * and can be used to undo everything done in this signal. */ signals[SETUP] = @@ -184,13 +184,13 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass) * @self: The #GtkSignalListItemFactory * @listitem: The #GtkListItem to bind * - * The ::bind signal is emitted when a new GtkListItem:item has been set + * The ::bind signal is emitted when a new #GtkListItem:item has been set * on the @listitem and should be bound for use. * * After this signal was emitted, the listitem might be shown in a #GtkListView * or other list widget. * - * The GtkSignalListItemFactory::unbind signal is the opposite of this signal + * The #GtkSignalListItemFactory::unbind signal is the opposite of this signal * and can be used to undo everything done in this signal. */ signals[BIND] = @@ -212,9 +212,9 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass) * @listitem: The #GtkListItem to unbind * * The ::unbind signal is emitted when a listitem has been removed from use - * in a list widget and its new GtkListItem:item is about to be unset. + * in a list widget and its new #GtkListItem:item is about to be unset. * - * This signal is the opposite of the GtkSignalListItemFactory::bind signal + * This signal is the opposite of the #GtkSignalListItemFactory::bind signal * and should be used to undo everything done in that signal. */ signals[UNBIND] = @@ -238,7 +238,7 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass) * The ::teardown signal is emitted when a listitem is about to be destroyed. * It is the last signal ever emitted for this @listitem. * - * This signal is the opposite of the GtkSignalListItemFactory::setup signal + * This signal is the opposite of the #GtkSignalListItemFactory::setup signal * and should be used to undo everything done in that signal. */ signals[TEARDOWN] = diff --git a/gtk/gtksingleselection.c b/gtk/gtksingleselection.c index 8c23d3c303..e072594d6a 100644 --- a/gtk/gtksingleselection.c +++ b/gtk/gtksingleselection.c @@ -36,8 +36,8 @@ * used by list widgets in GTK. * * Note that the selection is *persistent* -- if the selected item is removed - * and re-added in the same ::items-changed emission, it stays selected. In - * particular, this means that changing the sort order of an underlying sort + * and re-added in the same #GListModel::items-changed emission, it stays selected. + * In particular, this means that changing the sort order of an underlying sort * model will preserve the selection. */ struct _GtkSingleSelection @@ -570,11 +570,13 @@ gtk_single_selection_get_selected (GtkSingleSelection *self) * @self: a #GtkSingleSelection * @position: the item to select or #GTK_INVALID_LIST_POSITION * - * Selects the item at the given position. If the list does not have an item at - * @position or #GTK_INVALID_LIST_POSITION is given, the behavior depends on the - * value of the GtkSingleSelection:autoselect property: If it is set, no change - * will occur and the old item will stay selected. If it is unset, the selection - * will be unset and no item will be selected. + * Selects the item at the given position. + * + * If the list does not have an item at @position or + * #GTK_INVALID_LIST_POSITION is given, the behavior depends on the + * value of the #GtkSingleSelection:autoselect property: If it is set, + * no change will occur and the old item will stay selected. If it is + * unset, the selection will be unset and no item will be selected. **/ void gtk_single_selection_set_selected (GtkSingleSelection *self, @@ -618,8 +620,10 @@ gtk_single_selection_set_selected (GtkSingleSelection *self, /** * gtk_single_selection_get_selected_item: * @self: a #GtkSingleSelection - * - * Gets the selected item. If no item is selected, %NULL is returned. + * + * Gets the selected item. + * + * If no item is selected, %NULL is returned. * * Returns: (transfer none): The selected item */ @@ -703,9 +707,9 @@ gtk_single_selection_get_can_unselect (GtkSingleSelection *self) * If %TRUE, unselecting the current item via * gtk_selection_model_unselect_item() is supported. * - * Note that setting GtkSingleSelection:autoselect will cause the + * Note that setting #GtkSingleSelection:autoselect will cause the * unselecting to not work, so it practically makes no sense to set - * both at the same time the same time.. + * both at the same time the same time. **/ void gtk_single_selection_set_can_unselect (GtkSingleSelection *self, diff --git a/gtk/gtkstringlist.c b/gtk/gtkstringlist.c index daf1731372..5c04301c70 100644 --- a/gtk/gtkstringlist.c +++ b/gtk/gtkstringlist.c @@ -466,11 +466,11 @@ gtk_string_list_new (const char * const *strings) * Changes @self by removing @n_removals strings and adding @additions * to it. * - * This function is more efficient than gtk_string_list_insert() and + * This function is more efficient than gtk_string_list_append() and * gtk_string_list_remove(), because it only emits * #GListModel::items-changed once for the change. * - * This function takes a ref on each item in @additions. + * This function copies the strings in @additions. * * The parameters @position and @n_removals must be correct (ie: * @position + @n_removals must be less than or equal to the length -- 2.30.2